api

This month's API corner focuses on NT environment variables. By very definition of the limitations of the language, this article does not apply to JustBASIC, which does not support dll calls, rather you will require Liberty BASIC version 3.x or greater. Also note that this article applies only to the NT, Win2000 and XP operating systems. While Windows 95, 98 and ME have a form of environment variables, they are not accessed using the same API calls, as the underlying OS level is actually DOS based, and not built around the NT Kernel.

Environment Variables are special variables that are set on the OS level that are used by applications to describe various aspects of the OS. The best known environment variable is probably "PATH", which holds a string that describes the search path that the Operating System will traverse to find an executable or dll.

You can actually see the many variables that are part of your OS by opening a command prompt (go to START, select RUN and type "command" and press ENTER). Once the command prompt is open, type: "SET".

Here is a small extract of environment variables from my system:

ALLUSERSPROFILE=D:\Documents and Settings\All Users

APPDATA=D:\Documents and Settings\moorebj\Application Data

CLIENTNAME=Console

CommonProgramFiles=C:\Program Files\Common Files

ComSpec=C:\WINDOWS\system32\cmd.exe

HOMEDRIVE=C:

HOMESHARE=\\dataserver\userdirs

LOGONSERVER=\\DOMAINCTRL10

NUMBER_OF_PROCESSORS=1

OS=Windows_NT

Path= C:\WINDOWS\system32;C:\WINDOWS; C:\Program Files\Common Files\Adaptec Shared\SystemPATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH

PROCESSOR_ARCHITECTURE=x86

PROCESSOR_IDENTIFIER=x86 Family 6 Model 8 Stepping 10, GenuineIntel

PROCESSOR_LEVEL=6

PROCESSOR_REVISION=080a

ProgramFiles=C:\Program Files

PROMPT=$P$G

SESSIONNAME=Console

SystemDrive=C:

SystemRoot=C:\WINDOWS

Some of the really useful items that can be gathered from the Environment Variables include things like OS, User Name, Profile path, Windows location, etc.

The call required is GetEnvironmentVariableA which is part of kernel32. It requires three parameters:

Variable_name - a pointer to a string that contains the name of the variable you are interested in getting the value for. It is a good idea to pass null terminated strings, but in the case of this call if is not required.

Buffer - a pointer to a string that will contain the return value. This string buffer must be presized before making the call. It is a good idea to pass null terminated strings, but in the case of this call if is not required.

Buffer_len - a long which contains a numeric value that equals the length of the buffer.

The call returns a long value that represents the length of the string value returned in the string Buffer. The call will return a zero if the variable was not located.

I have encapsulated the call into the following function:


function GetEnvVar$(name$)
    'calls the api GetEnvironmentVariable to get the names environment variable
    
    lbuf$ = space$(255) + chr$(0)
    name$ = name$ + chr$(0)
    calldll #kernel32, "GetEnvironmentVariableA", name$ as ptr, _
                                                  lbuf$ as ptr, _
                                                  256 as long, _
                                                  result as long
    if result = 0 then
        GetEnvVar$ = "Environment Variable Not Found"
    else
        GetEnvVar$ = left$(lbuf$,result)
    end if
    
end function

Using the function is very straight forward. The demonstration program below shows its use coupled with a simple GUI. The function call and program are in the Public Domain. Enjoy!


'Demo of API call to get Environment Variable
'Placed into the Public domain on 10/15/04
'Original author: Brad Moore
'Created using Liberty Basic Workshop - thanks Alyce!
'Check out Liberty Basic at http://www.libertybasic.com

    'create the array that will contain the values for the combobox
    DIM Combo1$(10)
    a$ = "UserName UserProfile ProgramFiles windir OS Unknown" 
    for x = 1 to 6
        Combo1$(x) = word$(a$, x)
    next x

    'Setup the window
    NOMAINWIN
    WindowWidth = 529 : WindowHeight = 166
    'we want it centered
    UpperLeftX = INT((DisplayWidth-WindowWidth)/2)
    UpperLeftY = INT((DisplayHeight-WindowHeight)/2)

    'setup the controls
    groupbox    #main.group1, "Current Value", 20, 50, 480, 60
    statictext  #main.st1, "", 35, 75, 440, 25
    statictext  #main.st2, "Choose an environment variable:", 25, 20, 205, 20
    button      #main.go, "Go!",[go],UL, 450, 20, 45, 25
    combobox    #main.combo,Combo1$(),[loop], 240, 20, 200, 300

    Open "Environment Variables" for Window as #main
    #main "trapclose [quit]"
    #main.combo "selectindex 1"
    #main "font ms_sans_serif 11"
    #main.combo "font ms_sans_serif 11"


[loop]
    Wait

[quit]
    close #main : END

[go]
    #main.combo "selection? selected$"
    if selected$ <> "" then
        #main.st1 GetEnvVar$(selected$)
    end if
    wait


function GetEnvVar$(name$)
    'calls the api GetEnvironmentVariable to get the names environment variable
    
    lbuf$ = space$(255) + chr$(0)
    name$ = name$ + chr$(0)
    calldll #kernel32, "GetEnvironmentVariableA", name$ as ptr, _
                                                  lbuf$ as ptr, _
                                                  256 as long, _
                                                  result as long
    if result = 0 then
        GetEnvVar$ = "Environment Variable Not Found"
    else
        GetEnvVar$ = left$(lbuf$,result)
    end if
    
end function